~ chicken-core (master) /manual/Module (chicken locative)

 1[[tags: manual]]
 2[[toc:]]
 3
 4== Module (chicken locative)
 5
 6A ''locative'' is an object that points to an element of a containing object,
 7much like a ''pointer'' in low-level, imperative programming languages like ''C''. The element can
 8be accessed and changed indirectly, by performing access or change operations
 9on the locative. The container object can be computed by calling the
10{{locative->object}} procedure.
11
12Locatives may be passed to foreign procedures that expect pointer arguments.
13
14The following procedures are provided by the {{(chicken locative)}}
15module.
16
17=== make-locative
18
19<procedure>(make-locative OBJ [INDEX])</procedure>
20
21Creates a locative that refers to the element of the non-immediate object
22{{OBJ}} at position {{INDEX}}. {{OBJ}} may be a vector, pair, string, bytevector,
23SRFI-4 number-vector, or record structure. {{INDEX}} should be a fixnum.
24{{INDEX}} defaults to 0. Note that {{INDEX}} designates a character-position
25for string objects, not a byte offset.
26
27
28=== make-weak-locative
29
30<procedure>(make-weak-locative OBJ [INDEX])</procedure>
31
32Creates a ''weak'' locative. Even though the locative refers to an element of a container object,
33the container object will still be reclaimed by garbage collection if no other references
34to it exist.
35
36
37=== locative?
38
39<procedure>(locative? X)</procedure>
40
41Returns {{#t}} if {{X}} is a locative, or {{#f}} otherwise.
42
43
44=== locative-ref
45
46<procedure>(locative-ref LOC)</procedure>
47
48Returns the element to which the locative {{LOC}} refers. If the containing
49object has been reclaimed by garbage collection, an error is signalled.
50
51 (locative-ref (make-locative "abc" 1)) ==> #\b
52
53=== locative-set!
54
55<procedure>(locative-set! LOC X)</procedure><br>
56<procedure>(set! (locative-ref LOC) X)</procedure>
57
58Changes the element to which the locative {{LOC}} refers to {{X}}.
59If the containing
60object has been reclaimed by garbage collection, an error is signalled.
61
62
63=== locative->object
64
65<procedure>(locative->object LOC)</procedure>
66
67Returns the object that contains the element referred to by {{LOC}} or
68{{#f}} if the container has been reclaimed by garbage collection.
69
70 (locative->object (make-locative "abc" 1)) ==> "abc"
71
72---
73Previous: [[Module (chicken load)]]
74
75Next: [[Module (chicken memory)]]